Help/Other Topics/asTarget.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <meta http-equiv="Content-Style-Type" content="text/css">
   6 <title></title>
   7 <meta name="Generator" content="Cocoa HTML Writer">
   8 <meta name="CocoaVersion" content="824.42">
   9 <style type="text/css">
  10 p.p1 {margin: 0.0px 0.0px 0.0px 0.0px; font: 18.0px Helvetica}
  11 p.p2 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; min-height: 14.0px}
  12 p.p3 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica}
  13 p.p4 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 12.0px Helvetica; min-height: 14.0px}
  14 p.p5 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 9.0px Monaco}
  15 p.p6 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 9.0px Monaco; color: #a71e12}
  16 p.p7 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco}
  17 p.p8 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #a71e12}
  18 p.p9 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; min-height: 12.0px}
  19 span.s1 {font: 12.0px Helvetica}
  20 span.s2 {color: #0019b7}
  21 span.s3 {color: #000000}
  22 span.s4 {color: #a71e12}
  23 span.s5 {color: #606060}
  24 span.s6 {color: #326f17}
  25 span.Apple-tab-span {white-space:pre}
  26 </style>
  27 </head>
  28 <body>
  29 <p class="p1"><b>asTarget</b></p>
  30 <p class="p2"><br></p>
  31 <p class="p3"><b>Convert to a valid Node Target</b></p>
  32 <p class="p2"><br></p>
  33 <p class="p3">The classes listed below implement the method asTarget. This is used widely in the <b>Node</b> classes (<b>Group</b> and <b>Synth</b>) to convert non-Node objects to an appropriate target. This allows nil and instances of <b>Server</b> to be used as targets. This can be useful when writing classes which create nodes internally, but in most cases there should be little need to call asTarget in normal use.</p>
  34 <p class="p2"><br></p>
  35 <p class="p2"><br></p>
  36 <p class="p3"><b>Node</b> - Returns the instance of Node itself. The subclasses of <b>Node</b> (<b>Synth</b> and <b>Group</b>) are valid targets and require no conversion.</p>
  37 <p class="p2"><br></p>
  38 <p class="p2"><br></p>
  39 <p class="p3"><b>Server</b> - Returns a <b>Group</b> object representing the <b>default_group</b> of this instance of <b>Server</b>. Note that this object may not be identical with other objects representing the default group, but will be equivalent.</p>
  40 <p class="p4"><br></p>
  41 <p class="p5"><span class="s1"><span class="Apple-tab-span">    </span></span>s = <span class="s2">Server</span>.default;</p>
  42 <p class="p6"><span class="s3"><span class="Apple-tab-span">    </span>g = s.asTarget; </span>// the default group of s</p>
  43 <p class="p5"><span class="Apple-tab-span">     </span>h = s.defaultGroup; <span class="s4">// and again</span></p>
  44 <p class="p5"><span class="Apple-tab-span">     </span>g == h; <span class="Apple-tab-span">    </span><span class="s4">// true</span></p>
  45 <p class="p5"><span class="Apple-tab-span">     </span>g === h;<span class="Apple-tab-span">    </span><span class="s4">// false</span></p>
  46 <p class="p2"><br></p>
  47 <p class="p2"><br></p>
  48 <p class="p3"><b>Nil</b> - Returns a <b>Group</b> object representing the <b>default_group</b> of the current default <b>Server</b>.</p>
  49 <p class="p2"><br></p>
  50 <p class="p7"><span class="s1"><span class="Apple-tab-span">    </span></span>s = <span class="s2">Server</span>.default;</p>
  51 <p class="p7"><span class="Apple-tab-span">     </span>g = nil.asTarget;</p>
  52 <p class="p7"><span class="Apple-tab-span">     </span>g == s.defaultGroup; <span class="s4">// true</span></p>
  53 <p class="p2"><br></p>
  54 <p class="p2"><br></p>
  55 <p class="p3"><b>Integer</b> - Returns a <b>Group</b> object representing a group node on the current default <b>Server</b> with this <b>Integer</b> as its node ID number. <b>Note:</b> Although this can be convenient in some cases, it does not create the corresponding node on the default server, nor does it check to make sure that it exists. As well it does not directly access the server's NodeIDAllocator, so duplication of node IDs is possible. For these reasons this method should be used with care. When not dealing with the default Server, Group-basicNew is safer and simpler, as otherwise one needs to set the server instance variable to ensure correct targeting.</p>
  56 <p class="p2"><br></p>
  57 <p class="p8">/////// Showing the problems</p>
  58 <p class="p9"><br></p>
  59 <p class="p7"><span class="Apple-tab-span">     </span>s = <span class="s2">Server</span>.default;</p>
  60 <p class="p7"><span class="Apple-tab-span">     </span>s.boot;</p>
  61 <p class="p7"><span class="Apple-tab-span">     </span>g = s.nextNodeID.asTarget;</p>
  62 <p class="p8"><span class="s3"><span class="Apple-tab-span">    </span>x = </span><span class="s2">Synth</span><span class="s3">.head(g, </span><span class="s5">"default"</span><span class="s3">); <span class="Apple-tab-span">      </span></span>// but g doesn't exist on the server</p>
  63 <p class="p8"><span class="s3"><span class="Apple-tab-span">    </span>s.sendMsg(*g.addToHeadMsg); <span class="Apple-tab-span">        </span></span>// now it's sent to the default server, in the default group</p>
  64 <p class="p7"><span class="Apple-tab-span">     </span>x = <span class="s2">Synth</span>.head(g, <span class="s5">"default"</span>); <span class="Apple-tab-span">      </span><span class="s4">// now this works</span></p>
  65 <p class="p7"><span class="Apple-tab-span">     </span>x.free; g.free;</p>
  66 <p class="p9"><span class="Apple-tab-span">     </span></p>
  67 <p class="p8"><span class="s3"><span class="Apple-tab-span">    </span></span>// if not using the default Server Integer-asTarget can be problematic</p>
  68 <p class="p9"><span class="Apple-tab-span">     </span></p>
  69 <p class="p7"><span class="Apple-tab-span">     </span><span class="s2">Server</span>.default = <span class="s2">Server</span>.local;<span class="Apple-converted-space"> </span></p>
  70 <p class="p8"><span class="s3"><span class="Apple-tab-span">    </span></span><span class="s2">Server</span><span class="s3">.default.boot; <span class="Apple-tab-span">       </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span></span>// quit the default server</p>
  71 <p class="p7"><span class="Apple-tab-span">     </span>i = <span class="s2">Server</span>.internal; i.boot;</p>
  72 <p class="p7"><span class="Apple-tab-span">     </span>g = i.nextNodeID.asTarget;</p>
  73 <p class="p7"><span class="Apple-tab-span">     </span>i.sendMsg(*g.addToHeadMsg);<span class="Apple-tab-span"> </span><span class="Apple-tab-span">    </span><span class="s4">// seems to work, but...</span></p>
  74 <p class="p8"><span class="s3"><span class="Apple-tab-span">    </span>x = </span><span class="s2">Synth</span><span class="s3">.head(g, </span><span class="s5">"default"</span><span class="s3">); <span class="Apple-tab-span">      </span></span>// oops, this goes to the default server, so Group not Found</p>
  75 <p class="p8"><span class="s3"><span class="Apple-tab-span">    </span>g.server == </span><span class="s2">Server</span><span class="s3">.default;<span class="Apple-tab-span"> </span><span class="Apple-tab-span">    </span></span>// true, so that's the problem</p>
  76 <p class="p7"><span class="Apple-tab-span">     </span>g.server = i;</p>
  77 <p class="p8"><span class="s3"><span class="Apple-tab-span">    </span>x = </span><span class="s2">Synth</span><span class="s3">.head(g, </span><span class="s5">"default"</span><span class="s3">); <span class="Apple-tab-span">      </span></span>// now to the right place</p>
  78 <p class="p7"><span class="Apple-tab-span">     </span>x.free; g.free;</p>
  79 <p class="p9"><span class="Apple-tab-span">     </span></p>
  80 <p class="p8">/////// A more practical example</p>
  81 <p class="p9"><br></p>
  82 <p class="p7"><span class="Apple-tab-span">     </span>s = <span class="s2">Server</span>.default;</p>
  83 <p class="p7"><span class="Apple-tab-span">     </span>s.boot;</p>
  84 <p class="p7"><span class="Apple-tab-span">     </span>s.sendMsg(<span class="s6">\g_new</span>, x = s.nextNodeID);</p>
  85 <p class="p8"><span class="s3"><span class="Apple-tab-span">    </span></span>// ...</p>
  86 <p class="p9"><span class="Apple-tab-span">     </span></p>
  87 <p class="p8"><span class="s3"><span class="Apple-tab-span">    </span></span>// now if we need to use Node objects for some reason</p>
  88 <p class="p7"><span class="Apple-tab-span">     </span>y = <span class="s2">Synth</span>.head(x.asTarget, <span class="s5">"default"</span>);<span class="Apple-converted-space"> </span></p>
  89 <p class="p9"><span class="Apple-tab-span">     </span></p>
  90 <p class="p8"><span class="s3"><span class="Apple-tab-span">    </span></span>// this is simpler than Group.basicNew(s, x);, providing you're using the default server:</p>
  91 <p class="p7"><span class="Apple-tab-span">     </span>z = <span class="s2">Synth</span>.head(<span class="s2">Group</span>.basicNew(s, x), <span class="s5">"default"</span>);<span class="Apple-converted-space"> </span></p>
  92 <p class="p9"><span class="Apple-tab-span">     </span></p>
  93 <p class="p7"><span class="Apple-tab-span">     </span>y.free; z.free; x.asTarget.free;</p>
  94 <p class="p9"><br></p>
  95 </body>
  96 </html>